Tool Results

Every BindAI tool execution produces a ToolResult. ToolResult is the standard result object used by the Tool abstraction. It records whether execution succeeded, the value returned by the underlying Python function, and any error information produced during execution. This provides a predictable contract between tool execution and the rest of the framework.

ToolResult

ToolResult is a dataclass with three fields:

ToolResult(
    success: bool,
    value: Any = None,
    error: str | None = None,
)

The fields are:

Field	Description
`success`	Whether the tool executed successfully
`value`	The value returned by the underlying Python function
`error`	Error information when execution fails

ToolResult uses slots=True. The important distinction is that value contains successful tool output, while error contains the error information for failed execution.

How Tool Results Are Created

Tools automatically convert function execution into a ToolResult. For example:

from bindai import tool


@tool
def multiply(a: int, b: int) -> int:
    return a * b

When the tool is called:

result = multiply(4, 5)

print(result)

the result represents:

ToolResult(
    success=True,
    value=20,
    error=None,
)

The Python function only needs to return its normal Python value. You do not normally need to construct a ToolResult manually.

Successful Execution

When the underlying function completes successfully, Tool wraps its return value in a successful result. Conceptually:

value = function(*args, **kwargs)

return ToolResult(
    success=True,
    value=value,
)

For example:

@tool
def square(value: int) -> int:
    return value * value

Calling:

result = square(7)

produces:

ToolResult(
    success=True,
    value=49,
    error=None,
)

The original Python return value is available through result.value.

Failed Execution

If the underlying function raises an exception, the Tool abstraction converts the exception into a failed ToolResult. Conceptually:

try:
    value = function(*args, **kwargs)

    return ToolResult(
        success=True,
        value=value,
    )

except Exception as exc:
    return ToolResult(
        success=False,
        error=str(exc),
    )

For example:

@tool
def divide(a: int, b: int) -> float:
    return a / b

Calling:

result = divide(10, 0)

produces a failed result similar to:

ToolResult(
    success=False,
    value=None,
    error="division by zero",
)

The exact error string depends on the exception raised by the underlying function.

Checking Success

Applications can inspect the success field:

result = multiply(4, 5)

if result.success:
    print(result.value)
else:
    print(result.error)

This provides a simple way to distinguish successful execution from failure. A useful general pattern is:

if result.success:
    # Use result.value
    ...
else:
    # Handle result.error
    ...

Accessing the Returned Value

A successful tool return value is stored in value. For example:

@tool
def greet(name: str) -> str:
    return f"Hello, {name}!"


result = greet("Alice")

print(result.value)

The output is:

Hello, Alice!

The field is named value, not output. This distinction is important because AgentResult uses a different result interface.

Returning Different Python Values

A tool can return normal Python values.

Strings

@tool
def ping() -> str:
    return "Pong"

The result contains:

ToolResult(
    success=True,
    value="Pong",
)

Numbers

@tool
def square(value: int) -> int:
    return value * value

The result contains:

ToolResult(
    success=True,
    value=25,
)

Lists

@tool
def colors() -> list[str]:
    return [
        "red",
        "green",
        "blue",
    ]

The list is stored in:

result.value

Dictionaries

@tool
def profile() -> dict:
    return {
        "name": "Alice",
        "age": 28,
    }

The dictionary is stored in:

result.value

The ToolResult.value field accepts arbitrary Python values, so the underlying tool can return different value types. Choose return types that are useful and predictable for the application.

`None` as a Tool Value

A tool can also complete successfully without returning a meaningful value. For example:

@tool
def send_notification(message: str) -> None:
    print(message)

A successful execution can therefore contain:

ToolResult(
    success=True,
    value=None,
    error=None,
)

Do not interpret value=None by itself as a failure. Use result.success to determine whether execution succeeded.

Tool Exceptions

Tool exceptions are handled by the Tool abstraction. An exception raised by the underlying function is converted into a failed ToolResult. The resulting error information is derived from the exception. Conceptually:

ToolResult(
    success=False,
    value=None,
    error=str(exception),
)

This gives callers a consistent result object for successful and failed tool execution. For development and debugging, tools should still be written carefully so that unexpected programming errors are not silently ignored.

ToolExecutor

BindAI also provides ToolExecutor.

from bindai import ToolExecutor

ToolExecutor works with a ToolRegistry:

executor = ToolExecutor(registry)

It can execute a registered tool by name:

result = executor.execute(
    "multiply",
    4,
    5,
)

The execution result is represented as a ToolResult. This provides a lower-level execution path that does not require going through a complete agent request.

Unknown Tools

If ToolExecutor cannot find the requested tool in its registry, it returns a failed ToolResult. The result represents the failed lookup:

ToolResult(
    success=False,
    value=None,
    error="Unknown tool 'missing_tool'",
)

For example:

result = executor.execute("missing_tool")

The caller can handle the failure using the same ToolResult interface:

if result.success:
    print(result.value)
else:
    print(result.error)

This avoids requiring callers to handle a separate result type for an unknown registered tool name.

Tool Execution Flow

The current tool execution flow can be summarized as:

Python Function
      |
      v
    Tool
      |
      +-- Function succeeds
      |       |
      |       v
      |   ToolResult(
      |       success=True,
      |       value=...
      |   )
      |
      +-- Function raises exception
              |
              v
          ToolResult(
              success=False,
              error=...
          )

When using ToolExecutor:

Tool Name
   |
   v
ToolRegistry
   |
   +-- Tool found
   |      |
   |      v
   |   Tool.__call__()
   |      |
   |      v
   |   ToolResult
   |
   +-- Tool not found
          |
          v
      Failed ToolResult

ToolResult and Agents

ToolResult is specifically concerned with tool execution. AgentResult represents the result of an agent execution. They have different responsibilities and different APIs. For example, a tool result uses:

ToolResult(
    success=True,
    value=...,
    error=None,
)

An agent execution uses the AgentResult interface described in the Agent execution and Results documentation. Do not assume that fields from one result type are available on the other. In particular:

tool_result.value

should not be replaced with:

tool_result.output

when working with the current ToolResult API.

ToolResult and Workflows

Tools can also be used as part of workflow execution. A workflow can invoke a tool, inspect its result, and use the successful value in subsequent processing. Conceptually:

Workflow
   |
   v
Tool
   |
   v
ToolResult
   |
   +-- success --> Continue with value
   |
   +-- failure --> Handle error

The workflow decides how the tool result participates in the larger workflow state. ToolResult itself remains focused on the outcome of the individual tool execution.

ToolResult and External Integrations

Tools commonly wrap external operations such as:

API requests
Database operations
File operations
Search operations
Notifications
Service integrations

For example:

@tool
def lookup_customer(customer_id: int) -> dict: ...

The external operation can return a normal Python value. BindAI then exposes that value through:

result.value

If execution fails, the result can instead expose:

result.error

This keeps the tool result boundary consistent even when the implementation behind the tool changes.

Current API

The currently verified ToolResult API is:

ToolResult(
    success: bool,
    value: Any = None,
    error: str | None = None,
)

The available attributes are:

result.success
result.value
result.error

The current API does not define verified helper methods such as:

ToolResult.success()
ToolResult.failure()

Use the dataclass fields directly.

Result Handling Pattern

A simple result-handling pattern is:

result = executor.execute(
    "multiply",
    10,
    20,
)

if not result.success:
    print(f"Tool failed: {result.error}")
else:
    print(f"Tool returned: {result.value}")

This pattern keeps success and failure handling explicit. For application code, consider logging failures or propagating them to the appropriate workflow or agent layer rather than silently ignoring them.

Predictable Tool Outputs

Tool outputs should be designed with their callers in mind. Prefer predictable structures for operations that return structured information. For example:

@tool
def get_customer(customer_id: int) -> dict:
    return {
        "id": customer_id,
        "name": "Alice",
        "active": True,
    }

The caller can then reliably inspect:

result.value["name"]

For more complex applications, structured Python objects or clearly defined dictionaries can make downstream processing easier.

Error Messages

Error messages should provide useful information without exposing sensitive implementation details. For example:

@tool
def fetch_order(order_id: int): ...

A useful application-level error might communicate that the requested order could not be retrieved. Avoid exposing:

API keys
Access tokens
Passwords
Connection strings
Sensitive personal information
Internal credentials

Tool results can flow back into an agent or external application, so error content should be treated as application-visible data.

Best Practices

Return normal Python values from tool functions.
Let Tool wrap successful return values into ToolResult.
Check result.success before using result.value.
Inspect result.error when execution fails.
Keep tool return values predictable.
Use clear and useful error messages.
Avoid exposing secrets or sensitive internal details through errors.
Keep tool functions focused on one responsibility.
Test both successful and failed execution.
Test unknown-tool behavior when using ToolExecutor.
Do not rely on an output field for ToolResult; use value.
Do not assume ToolResult and AgentResult have identical APIs.
Do not depend on undocumented result helper methods.

Complete Example

from bindai import Agent, tool


@tool(
    name="multiply",
    description="Multiply two integers.",
)
def multiply(a: int, b: int) -> int:
    return a * b


agent = (
    Agent.builder()
    .name("calculator")
    .model("openai:gpt-4.1-mini")
    .instructions("Use the multiply tool when arithmetic is required.")
    .tool(multiply)
    .build()
)

result = agent.run("What is 14 × 9?")

if result.success:
    print(result.output)
else:
    print(result.error)

The agent-level result is an AgentResult, while the individual tool execution uses ToolResult. When working directly with a ToolResult, the successful tool value is accessed through:

tool_result.value

This distinction keeps the APIs of tool execution and agent execution separate.

Summary

ToolResult is BindAI’s standard result object for tool execution. The current result structure is:

ToolResult
├── success
├── value
└── error

A successful Python function return value is stored in value. An execution failure is represented by success=False and error information in error. The current public interface is intentionally small:

result.success
result.value
result.error

This provides a simple and consistent contract for executing tools, handling failures, and passing tool results into larger agent or workflow executions.

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

03.4 tool results

Tool Results

ToolResult

How Tool Results Are Created

Successful Execution

Failed Execution

Checking Success

Accessing the Returned Value

Returning Different Python Values

Strings

Numbers

Lists

Dictionaries

`None` as a Tool Value

Tool Exceptions

ToolExecutor

Unknown Tools

Tool Execution Flow

ToolResult and Agents

ToolResult and Workflows

ToolResult and External Integrations

Current API

Result Handling Pattern

Predictable Tool Outputs

Error Messages

Best Practices

Complete Example

Summary

​Tool Results

​ToolResult

​How Tool Results Are Created

​Successful Execution

​Failed Execution

​Checking Success

​Accessing the Returned Value

​Returning Different Python Values

​Strings

​Numbers

​Lists

​Dictionaries

​None as a Tool Value

​Tool Exceptions

​ToolExecutor

​Unknown Tools

​Tool Execution Flow

​ToolResult and Agents

​ToolResult and Workflows

​ToolResult and External Integrations

​Current API

​Result Handling Pattern

​Predictable Tool Outputs

​Error Messages

​Best Practices

​Complete Example

​Summary

Tool Results

ToolResult

How Tool Results Are Created

Successful Execution

Failed Execution

Checking Success

Accessing the Returned Value

Returning Different Python Values

Strings

Numbers

Lists

Dictionaries

`None` as a Tool Value

Tool Exceptions

ToolExecutor

Unknown Tools

Tool Execution Flow

ToolResult and Agents

ToolResult and Workflows

ToolResult and External Integrations

Current API

Result Handling Pattern

Predictable Tool Outputs

Error Messages

Best Practices

Complete Example

Summary